.TH LIBPFM 3  "November, 2002" "" "Linux Programmer's Manual"
.SH NAME
pfm_find_event, pfm_find_event_byname, pfm_find_event_bycode, pfm_find_event_bycode_next \- search for events
.SH SYNOPSIS
.nf
.B #include <perfmon/pfmlib.h>
.sp
.BI "int pfm_find_event(char *"str ", int *"desc);
.BI "int pfm_find_event_byname(char *"v ", int *"desc);
.BI "int pfm_find_event_bycode(int "code ", int *"desc);
.BI "int pfm_find_event_bycode_next(int "desc ", int "code ", int *"desc);
.sp
.SH DESCRIPTION
The PMU counters can be programmed to measure the number of occurrences
of certain events. The number of events varies from one implementation
to the other. Each event has a name and a code which is used to program
the actual PMU register. Not all event can necessarily be programmed on
any of the available counters due to hardware constraints.
.sp
The library does not directly expose the event code to user applications
because it is not necessary. Instead applications used names to
query the library for particular information about events. Given
a name, the library returns an opaque descriptor to the applications. 
Each descriptor is unique and has no relationship to the event code.
All functions requires the library to be properly initialized.
.sp
The set of functions described here allows to get an event descriptor
given either the name of the event or its code. Several events can
share the same code but have different names. In the current
implementation of the PMU, an event code is composed of a base
code (called event select) and a umask. The combination of the two
is guaranteed unique. The umask is not an architected feature and
as such is not part of the generic interface of this library.
.sp
The \fBpfm_find_event\fR function is a general purpose search routine.
Given a string it returns the descriptor of the corresponding event.
The string can represent an event name or an event code in ASCII form.
Note that the code can be represented in decimal or hexadecimal.
.sp
In contrast \fBpfm_find_event_byname\fR searches for an event
by interpreting the \fBname\fR argument as the name event only.
.sp 
Similarly, \fBpfm_find_event_bycode\fR searches for an event given
its \fBcode\fR represented as an integer. 
.sp
Because there can be several events with the same code, the library
provides the \fBpfm_find_event_bycode_next\fR to search for other
events with the same code. Given an event \fBe\fR and a \fBcode\fR,
this function will look for the next event with the same code.
It is not necessary to have called \fBpfm_find_event_bycode\fR prior
to calling this function. This function is fully threadsafe as it does
not maintain any state between calls.
.SH RETURN
All functions return whether or not the call was successful.
A return value of \fBPFMLIB_SUCCESS\fR indicates success, 
otherwise the value is the error code.
.SH ERRORS
.B PFMLIB_ERR_NOINIT
the library has not been initialized properly.
.TP
.B PFMLIB_ERR_INVAL
the event descriptor is invalid, or the pointer argument is NULL.
.TP
.B PFMLIB_ERR_NOTFOUND
no matching event was found.
.SH AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
.PP
